import { Button } from '../../components';

<article>

<Title>
  Button
</Title>

Buttons are interactive elements used to take an action, such as submitting a form or opening a dialog.

<div className="center">
    <Button />
</div>

</article>

<article>

## Functionality

As far as functionality goes, you get [a lot of stuff](https://www.w3.org/TR/wai-aria-practices/#keyboard-interaction-3) for free by using the native [`<button>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button) element. This should be your first choice.

### Hover state

Indicates that the button is interactive when hovered with the mouse.

### Active state

Indicates that the button is pressed down.

### Focus state

Indicates that the focus in the document is currently on the button.

> For the sake of aesthetics, it can be tempting to remove default browser focus styles with `outline: 0;` <br /><br />
> Do not do this before adding your own custom focus styles!

### Disabled state

Indicates that the button is not interactive.

If necessary, used in combination with a <Link href="/play/tooltip">Tooltip</Link> to provide a brief explanation on hover.

### Loading state

Indicates that the action taken via the button is asynchronous and will respond in a given amount of time.

Visually, it is common that a spinner is shown inside the button.
Make sure that the button itself is not expanding in width or height while in this state.

### Responsive

Based on the [W3 Success Criterion for Target Size](https://www.w3.org/TR/WCAG21/#target-size), buttons should adapt to pointer inputs by expanding in size to a minimum of `44px`.
Optionally, buttons on mobile can also become block level full width elements.

</article>

<article>

## Best practices

- Always use the native [`<button>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button) element.
- Clearly distinguish the hierarchy of buttons with different variants.
- Write a button label that is succinct and short.
- Provide an [`aria-label`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-label_attribute) for buttons that don't contain text (e.g. icon buttons).

</article>

<article>

## Implementation

### Link buttons

When building your component, keep in mind that buttons can often be designed to act like a link.

A common pattern in React is for the component to expose an `as` prop which changes the rendered element
of the component, while keeping the visual the same.

```jsx
<Button as="a">Open</Button>
```

### `div` buttons

Sometimes, you might be tempted to do this:

```jsx
<div onClick={onClick}>Open</div>
```

By doing so, you lose a lot of the default behaviour baked into `<button>`.
**Avoid this at all cost and use the native element instead.**

_Although_, there may be a case where you want to create a component with nested buttons:


```jsx
function Tag({ onSelect, onRemove }) {
  return (
      <button onClick={onSelect}>
          Apple
          <button onClick={onRemove}>x</button>
      </button>
  );
}
```

This would not qualify as valid HTML, so you're gonna have to make the parent element a `div`.

In which case, you should be mindful to re-implement existing behaviour according to the [WAI-ARIA spec for Button](https://www.w3.org/TR/wai-aria-practices/#button):

```jsx
function DivButton({
  children,
  'aria-label': ariaLabel,
  disabled,
  onClick,
}) {
  function onKeyDown(e) {
      if (disabled) {
          return;
      }
      if (e.key === 'Enter' || e.key === ' ') {
         onClick();
      }
  }
  return (
      <div
          tabIndex={0}
          role="button"
          onKeyDown={onKeyDown}
          {...!disabled && { onClick }}
          {...ariaLabel && { ariaLabel }}
          aria-disabled={disabled ? 'true' : 'false'}
      >
          {children}
      </div>
  );
}
```

Oof... that's a lot of stuff to cover. I hope you never have to do this! 😬


</article>

<article>

## Accessibility

The accessibility requirements for this component are defined by the [WAI-ARIA Practices for Button](https://www.w3.org/TR/wai-aria-practices/#button):

- [Keyboard Interaction](https://www.w3.org/TR/wai-aria-practices/#keyboard-interaction-3)
- [WAI-ARIA Roles, States, and Properties](https://www.w3.org/TR/wai-aria-practices/#wai-aria-roles-states-and-properties-3)

</article>

<article>

## Resources

- [WAI-ARIA Practices — Button](https://www.w3.org/TR/wai-aria-practices/#button)

</article>
